home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #1 / Amiga Plus CD - 2000 - No. 1.iso / Tools / Text / Edit / GoldED-Demo / installdata / golded / developer / syntax / autodoc / scanlib.doc
Encoding:
Text File  |  1999-12-03  |  11.0 KB  |  325 lines
  1. TABLE OF CONTENTS
  2.  
  3. scanlib.library/MountScanner
  4. scanlib.library/StartScanner
  5. scanlib.library/CloseScanner
  6. scanlib.library/FlushScanner
  7. scanlib.library/SetupScanner
  8. scanlib.library/BriefScanner
  9. scanlib.library/ParseLine
  10. scanlib.library/UnparseLines
  11. scablib.library/ParseSection
  12.  
  13. scanlib.library/MountScanner               scanlib.library/MountScanner
  14.  
  15.     NAME
  16.         MountScanner - Return scanner description
  17.  
  18.     SYNOPSIS
  19.         parserdata = MountScanner(void)
  20.            D0
  21.  
  22.         struct ParserData *MountScanner(void)
  23.  
  24.     FUNCTION
  25.         This function is called before a syntax parser is used for the first
  26.         time. The result is used by the editor to determine if a parser is
  27.         configurable. The parser returns a description of its abilities or
  28.         NULL to signal failure.
  29.  
  30.     INPUTS
  31.  
  32.     RESULTS
  33.         Parser description or NULL on error.
  34.  
  35.     SEE ALSO
  36.         StartScanner, CloseScanner
  37.  
  38.     BUGS
  39.  
  40. scanlib.library/StartScanner               scanlib.library/StartScanner
  41.  
  42.     NAME
  43.         StartScanner - Start scanner for a new text
  44.  
  45.     SYNOPSIS
  46.         parserHandle = StartScanner(globalConfigPtr, editConfigPtr, syntaxStack, syntaxSetup)
  47.  
  48.         struct ParserHandle *StartScanner(struct GlobalConfig *, struct EditConfig *, struct SyntaxChunk *, struct SyntaxSetup *)
  49.                  D0                               A0                       A1                D0                     D1
  50.     FUNCTION
  51.         This function is called by the editor after a new text buffer has
  52.         been created to start syntax parsing (e.g. after loading a file). The
  53.         scanner returns a non-NULL handle or NULL to indicate failure. The
  54.         handle is later passed back to the parser during most function calls.
  55.         This function also provides the parser with an empty syntax stack
  56.         (SyntaxChunk array) allocated by the editor. The scanner is
  57.         encouraged to use this stack during subsequent parser calls instead
  58.         of allocating its own storage (the array is guaranteed to be of
  59.         sufficient size). Note: Syntax parsers shouldn't parse any text in
  60.         this function.
  61.  
  62.     INPUTS
  63.         globalConfigPtr - a pointer to global preferences of the editor
  64.         editConfigPtr   - a pointer to a text buffer (or NULL)
  65.         syntaxStack     - syntax stack provided by the editor
  66.         syntaxSetup     - syntax parser setup
  67.  
  68.     RESULTS
  69.         parser handle or NULL
  70.  
  71.     SEE ALSO
  72.         CloseScanner, FlushScanner
  73.  
  74.     BUGS
  75.  
  76. scanlib.library/CloseScanner               scanlib.library/CloseScanner
  77.  
  78.     NAME
  79.         failure = CloseScanner - Announce removal of a text buffer
  80.  
  81.     SYNOPSIS
  82.         failure = CloseScanner(parserHandle)
  83.           D0                       A0
  84.  
  85.         ULONG failure = CloseScanner(struct ParserHandle *)
  86.  
  87.     FUNCTION
  88.         This function is called if a text buffer is about to be closed. The
  89.         scanner is supposed to free global data related to the buffer. The
  90.         scanner is not supposed to unparse lines - there will be additional
  91.         UnparseLines() calls if there are lines to be unparsed (these calls
  92.         may arrive after the scanner has been closed already due to the
  93.         asynchronous design of the editor).
  94.  
  95.     INPUTS
  96.         parserHandle - handle as returned by StartScanner()
  97.  
  98.     RESULTS
  99.         failure - return code. Non-NULL values signal error.
  100.  
  101.     SEE ALSO
  102.         MountScanner, StartScanner, FlushScanner
  103.  
  104.     BUGS
  105.  
  106. scanlib.library/FlushScanner               scanlib.library/FlushScanner
  107.  
  108.     NAME
  109.         FlushScanner - Flush local data
  110.  
  111.     SYNOPSIS
  112.         FlushScanner(parserHandle)
  113.  
  114.         void FlushScanner(struct ParserHandle *)
  115.                                    A0
  116.     FUNCTION
  117.         This function is called to make the scanner free as much memory as
  118.         possible without affecting parsing (e.g. flush caches)
  119.  
  120.     INPUTS
  121.         parserHandle - handle as returned by StartScanner()
  122.  
  123.     RESULTS
  124.  
  125.     SEE ALSO
  126.         StartScanner, CloseScanner
  127.  
  128.     BUGS
  129.  
  130. scanlib.library/SetupScanner               scanlib.library/SetupScanner
  131.  
  132.     NAME
  133.         SetupScanner - Set scanner preferences
  134.  
  135.     SYNOPSIS
  136.         SetupScanner(globalConfigPtr)
  137.  
  138.         void SetupScanner(struct GlobalConfig *)
  139.                                   A0
  140.     FUNCTION
  141.         This function is called if the user wants to set the parser's
  142.         preferences. Suggested action is to open a configuration dialog on
  143.         the editor's screen.
  144.  
  145.     INPUTS
  146.         globalConfigPtr - A pointer to global preferences of the editor
  147.  
  148.     RESULTS
  149.  
  150.     SEE ALSO
  151.  
  152.     BUGS
  153.  
  154. scanlib.library/BriefScanner               scanlib.library/BriefScanner
  155.  
  156.     NAME
  157.         BriefScanner - Notify scanner
  158.  
  159.     SYNOPSIS
  160.         refreshrequest = BriefScanner(parserHandle, scannerNotify)
  161.  
  162.         struct RefreshRequest *BriefScanner(struct ParserHandle *, struct ScannerNotify *)
  163.                   D0                         A0                               A1
  164.  
  165.     FUNCTION
  166.         This function is called by the editor after a text has been modified.
  167.         UnparseLines() has already been called for all lines in the damage
  168.         area. The editor is going to refresh the damage area. We are supposed
  169.         to check whether the last operation has affected syntax highlighting
  170.         of lines beyond the damage area (e.g. if the first line of a comment
  171.         has been deleted). We are expected to unparse affected lines beyond
  172.         the damage area on our own. Besides, we will have to request a
  173.         display refresh for those lines (if any). This function supports
  174.         development of context scanners, i.e. scanners beeing able to
  175.         recognize syntax elements consisting of multiple lines. The scanner
  176.         should return a display refresh request or NULL if a standard damage
  177.         area refresh is sufficient. The editor will refresh (a) the damage
  178.         region and (b) the region described by the display refresh. The
  179.         regions may overlap.
  180.  
  181.     INPUTS
  182.         parserHandle  - handle as returned by StartScanner()
  183.         scannerNotify - scanner notification:
  184.  
  185.             sn_Class   = SCANNER_NOTIFY_MODIFIED:
  186.             sn_Line    = line number of first modification
  187.             sn_Lines   = number of modified lines still visible
  188.             sn_Removed = number of lines deleted during operation
  189.  
  190.             Class description: a block of lines has been modified. Lines
  191.             have been deleted, inserted or replaced.
  192.  
  193.  
  194.     RESULTS
  195.         refreshrequest - display refresh request
  196.  
  197.     SEE ALSO
  198.         UnparseLines
  199.  
  200.     BUGS
  201.  
  202.  
  203. scanlib.library/ParseLine                  scanlib.library/ParseLine
  204.  
  205.     NAME
  206.         ParseLine - Parse a line
  207.  
  208.     SYNOPSIS
  209.         syntaxStack = ParseLine(parserHandle, line, lineNode)
  210.  
  211.         struct SyntaxStack *ParseLine(struct ParserHandle *, struct LineNode *, line);
  212.                D0                                A0                 A1           D0
  213.  
  214.     FUNCTION
  215.         This function is called if a line has to be parsed. The editor will
  216.         call this function for each line during a display refresh, so it
  217.         better be fast. The scanner is expected to return a syntax
  218.         description. The scanner may write the description to the syntax
  219.         stack obtained during a prior StartScanner() call or to a private
  220.         memory area. A syntax stack is a 0-terminated array of structures
  221.         describing start, length and level of syntax elements within the
  222.         line. Non-NULL levels are tanslated into colors by the editor
  223.         according to syntax highlighting preferences. Sections of a line not
  224.         described by a syntax scanner default to be displayed as standard
  225.         text (syntax level 0).
  226.  
  227.         Restrictions:
  228.  
  229.         1. A stack may not contain level 0 elements (0 terminates stack)
  230.         2. Parsers may not set a level for leading spaces or leading tabs
  231.         3. Parsers may not set a level for trailing spaces or trailing tabs
  232.         4. Parsers may not set a level for sections beyond the end of line
  233.         5. Parsers may not parse fold headers
  234.         6. Syntax elements have to be sorted according to the start position
  235.  
  236.         This function is expected to return a syntax stack pointer if syntax
  237.         levels above 0 (ie. non-standard text) have been detected within the
  238.         line. Usage of a syntax cache is suggested to speed up output: each
  239.         line node containes a user data slot reserved for usage by a syntax
  240.         scanner. A scanner might use this slot to buffer the results of a
  241.         prior parser pass. Or to remember whether syntax elements have been
  242.         found at all and thus speed up future parser calls related to the
  243.         same line. The scanner is notified before and after lines are/have
  244.         been changed or removed to keep the cache up-to-date and valid
  245.         (UnparseLines, BriefScanner). The Scanner is notified before a
  246.         display refresh (ParseSection).
  247.  
  248.     INPUTS
  249.         parserHandle - handle as returned by StartScanner()
  250.         line         - line number
  251.         lineNode     - line data:
  252.  
  253.             lineNode->Text - line's text
  254.             lineNode->Len  - line's length
  255.  
  256.     RESULTS
  257.         syntaxStack - pointer to syntax stack or NULL (no highlighted elements)
  258.  
  259.     SEE ALSO
  260.         UnparseLines, ParseSection, BriefScanner, ParseSection
  261.  
  262.     BUGS
  263.  
  264.  
  265. scanlib.library/UnparseLines               scanlib.library/UnparseLines
  266.  
  267.     NAME
  268.         UnparseLines - Unparse lines
  269.  
  270.     SYNOPSIS
  271.         UnparseLines(lineNode, lines)
  272.  
  273.         void UnparseLines(struct LineNode *, ULONG)
  274.                                 A0            D0
  275.  
  276.     FUNCTION
  277.         This function is called before lines are deleted or modified. The
  278.         scanner is supposed to free private data attached to the UserData
  279.         slot of the lines (e.g. results of a prior parser pass if a caching
  280.         algorithm is used). UserData HAS TO BE SET TO NULL. Folded blocks
  281.         have to be unparsed, too. The scanner may not reparse any lines,
  282.         parsing should be restricted to BriefScanner() calls.
  283.  
  284.     INPUTS
  285.         lineNode - line data of first line
  286.         lines    - number of lines to be unparsed
  287.  
  288.     RESULTS
  289.  
  290.     SEE ALSO
  291.         ParseLine, BriefScanner
  292.  
  293.     BUGS
  294.  
  295. scanlib.library/ParseSection               scanlib.library/ParseSection
  296.  
  297.     NAME
  298.         ParseSection - Display refresh notification
  299.  
  300.     SYNOPSIS
  301.         syntaxStack = ParseSection(parserHandle, lineNode, lines)
  302.  
  303.         void  ParseSection(struct ParserHandle *, struct LineNode *, ULONG);
  304.                                      A0                  A1            D0
  305.  
  306.     FUNCTION
  307.         This function is called before a display refresh if more than one line
  308.         is to be displayed. Syntax scanners may or may not preparse the lines
  309.         to be displayed and attach private data to the UserData field of the
  310.         text lines. A scanner might use this data during subsequent
  311.         ParseLine() calls to speed up syntax processing, thus implementing a
  312.         "syntax chache".
  313.  
  314.     INPUTS
  315.         parserHandle - handle as returned by StartScanner()
  316.         lineNode     - line data: lineNode->Text, lineNode->Len
  317.         lines        - lines to be displayed
  318.  
  319.     RESULTS
  320.  
  321.     SEE ALSO
  322.         ParseLine
  323.  
  324.     BUGS
  325.